## 
"""
FastAPI应用主文件
展示如何集成灵活的认证系统
"""

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from app.core.config import settings
from app.core.middleware import setup_auth_middleware
from app.core.exceptions import setup_global_exception_handler

from app.api.base.system import router as system_router
from app.api.base.auth_examples import router as auth_router
from app.api.base.database import router as database_router
from app.utils.app_log import logger
from app.api import api_router


def register_routers(app: FastAPI, prefix: str = "/api"):
    app.include_router(api_router, prefix=prefix)


def create_app() -> FastAPI:
    """
    创建FastAPI应用实例
    
    Returns:
        FastAPI: 配置好的应用实例
    """
    
    # 创建FastAPI应用
    app = FastAPI(
        title="FastAPI通用基础项目",
        description="支持灵活认证控制的FastAPI基础项目",
        version="1.0.0",
        docs_url="/docs" if settings.debug else None,
        redoc_url="/redoc" if settings.debug else None,
    )
    
    # 设置全局异常处理器
    setup_global_exception_handler(app)
    
    # 设置CORS 跨域策略
    app.add_middleware(
        CORSMiddleware,
        allow_origins=settings.cors_origins,
        allow_credentials=True,
        allow_methods=["*"],
        allow_headers=["*"],
    )
    
    # 根据需要设置认证中间件  
    # 有三种方式可以选择：
    
    # 方式1：严格认证中间件（除白名单外的所有路由都需要认证）
    # setup_auth_middleware(app, middleware_type="strict")
    
    # 方式2：可选认证中间件（尝试解析token，但不强制要求）
    # setup_auth_middleware(app, middleware_type="optional")
    
    # 方式3：不使用全局中间件，通过依赖注入或装饰器在路由级别控制
    # 这是最灵活的方式，推荐使用   使用Depends注入或装饰器 < 学习一下写法 >
    
    # 方式1的扩展 。添加额外的排除路径示例
    # extra_exclude_paths = ["/api/v1/public/*", "/health"]
    # setup_auth_middleware(app, middleware_type="strict", exclude_paths=extra_exclude_paths)
    
    register_routers(app, prefix="/api")


    
    return app


# 创建应用实例
app = create_app()